Node / ReticulumProjects / MeshChatX.git / files / docs / en / identity-and-security.md

Displaying Raw • View rendered • Download

Tc9d1d9# Identities, privacy, and security

MeshChatX separates cryptographic identities, network security, and optional privacy controls. This page summarises how they interact.

Tc9d1d9## Identities

Each identity is a Reticulum key pair with its own:

Tff7b72- SQLite database and LXMF router directory

Tff7b72- Settings in the Ta5d6ff`config` table via Ta5d6ff`ConfigManager`

Tff7b72- Storage path under Ta5d6ff`storage/identities/<identity_hash>/`

Create, import, or switch identities from **Identities**. Only one identity is active in the UI at a time. Switching runs a teardown path so routers and managers do not leak state.

Shared resources include the Reticulum process and interface configuration in Ta5d6ff`~/.reticulum` unless you override paths.

Tc9d1d9## Announces

MeshChatX tracks announces for aspects such as:

| Aspect | Meaning |

| ------------------- | --------------------------------- |

| Ta5d6ff`lxmf.delivery` | Peer accepts LXMF messages |

| Ta5d6ff`lxst.telephony` | Peer accepts LXST calls |

| Ta5d6ff`lxmf.propagation` | Propagation node |

| Ta5d6ff`nomadnetwork.node` | NomadNet page server |

| Ta5d6ff`rrc.hub` | Relay chat hub (when RRC enabled) |

| Ta5d6ff`map-data-v1` | Published GeoJSON/KML/KMZ packs |

Announce records store signal metadata and parsed app data for display names and icons.

Tc9d1d9## Web UI authentication

Optional HTTP basic authentication is enabled with Ta5d6ff`--auth` or Ta5d6ff`MESHCHAT_AUTH=true`. Sessions use encrypted cookies. Mutating API requests require CSRF tokens.

Access attempts are logged. Repeated failures can trigger lockout when auth is enabled.

Reset a forgotten password with Ta5d6ff`--reset-password` or Ta5d6ff`MESHCHAT_RESET_PASSWORD=true`, then set a new password in the UI.

Tc9d1d9### Demo mode and ALTCHA

Ta5d6ff`MESHCHAT_DEMO_MODE=1` (or Ta5d6ff`--demo`) enables a public showcase profile: privacy mode on, plugins off, no outbound announces, and a default-deny HTTP mutation policy with mesh send blocked. Status reports Ta5d6ff`demo_mode: true`.

When Ta5d6ff`MESHCHAT_ALTCHA_ENABLED=1`, login and setup require a valid [Tff7b72ALTCHA](Te6edf3https://altcha.org/docs/v2/widget-v3/) proof-of-work payload (widget v3, server challenges use Ta5d6ff`PBKDF2/SHA-256` by default). Set Ta5d6ff`MESHCHAT_ALTCHA_HMAC_KEY` to a long random secret on the server. Optional Ta5d6ff`MESHCHAT_ALTCHA_COST` tunes PoW difficulty. The widget loads from the bundled Ta5d6ff`altcha` npm package and fetches challenges from Ta5d6ff`/api/v1/auth/altcha/challenge`.

Ta5d6ff`MESHCHAT_AUTH_PAGE_HINT` sets optional plain text on the login page (independent of demo mode). Demo Docker compose defaults to username and password hints for the showcase account.

Ta5d6ff`MESHCHAT_AUTH_BYPASS=1` skips session auth for local testing only. Do not use it on internet-facing deployments.

Tc9d1d9## Transport security

Tff7b72- HTTPS and WSS are on by default.

Tff7b72- Self-signed certificates are generated per identity when custom PEM files are missing.

Tff7b72- Pass Ta5d6ff`--ssl-cert` and Ta5d6ff`--ssl-key` for managed certificates.

Tff7b72- Use Ta5d6ff`--no-https` only on trusted loopback setups.

Electron loads the UI from the local HTTPS origin served by the embedded backend.

Tc9d1d9## IP allowlisting

Ta5d6ff`app_security_settings` can restrict which client IPs may use the web UI. Combine with auth when exposing the service beyond localhost.

Tc9d1d9## Privacy mode

**Privacy mode** blocks outbound HTTP from MeshChatX features that would otherwise call the public internet. Translation and similar tools respect this flag.

Privacy mode does not disable Reticulum mesh traffic. It limits clearnet fetches from the app itself.

Tc9d1d9## Linux sandboxing

On Linux, MeshChatX can enable two complementary in-process sandboxes when supported:

Tff7b72- **Landlock** restricts filesystem paths the backend may use. User-local pipx tools (for example Argos Translate under Ta5d6ff`~/.local`) need explicit read and sometimes write roots. See **Linux sandboxing** in Platform guides.

Tff7b72- **Seccomp-BPF** installs a syscall denylist (via libseccomp) that blocks kernel-admin and related calls a mesh client does not need.

Both auto-enable when available and fall back to a no-op when the platform, kernel, or libraries cannot support them. Override with:

Tff7b72- Ta5d6ff`MESHCHAT_LANDLOCK=0` or Ta5d6ff`1`

Tff7b72- Ta5d6ff`MESHCHAT_SECCOMP=0` or Ta5d6ff`1`

Android never enables these in-process sandboxes (the Android app seccomp policy already constrains the process, and Landlock syscalls are blocked there).

See **Linux sandboxing** in Platform guides for optional Firejail and Bubblewrap wrappers around the host install.

Tc9d1d9## Windows Electron AppContainer

Windows desktop builds can spawn the Python backend inside an LPAC AppContainer when Ta5d6ff`MESHCHAT_APPCONTAINER=1`. Default installs start the backend directly without that wrapper. Check Ta5d6ff`/api/v1/server/security` for Ta5d6ff`appcontainer_active` when debugging sandbox-related SQLite or filesystem errors on Windows.

Tc9d1d9## Blocking and filtering

Use **Blocked** for specific destination hashes. Combine with sieve filters, message blocklists, and LXMF stamp policies described in **LXMF messaging**.

Tc9d1d9## Data backup

Database backups land in Ta5d6ff`database-backups/`. Before a schema upgrade, MeshChatX writes a Ta5d6ff`backup-pre-migrate-v*-to-v*.zip` in that folder unless Ta5d6ff`MESHCHAT_SKIP_PRE_MIGRATE_BACKUP=1`. After a successful migration it runs Ta5d6ff`PRAGMA quick_check` and keeps the five newest pre-migrate zips (override with Ta5d6ff`MESHCHAT_PRE_MIGRATE_BACKUP_KEEP`, Ta5d6ff`0` disables pruning). If the stored schema version is newer than this build supports, startup refuses to migrate. Only one process should use a given identity storage directory at a time (storage lock). Roll back by restoring a backup zip and running an older MeshChatX build. Export snapshots from **About** or the API. Electron crash recovery can offer restore when integrity checks fail.

CLI examples:

Ta5d6ff```Ta5d6ffbash

meshchatx --list-backups

meshchatx --export-backup /path/to/export.zip

meshchatx --export-backup backup-20260101-120000.zip /path/to/copy.zip

meshchatx --restore-db /path/to/backup.zip

Ta5d6ff```

Tc9d1d9## Integrity checks

Startup integrity verification runs in packaged Electron builds and can be triggered from the backend. Failed checks surface recovery options instead of silently corrupting data.

Tc9d1d9## Plugin signing and trust

Packaged plugins may include a Reticulum Signature (Ta5d6ff`.rsg`) over a canonical ZIP payload (sorted paths, fixed 1980-01-01 mtimes, signature file excluded). MeshChatX plugin signing writes Ta5d6ff`meshchatx.plugin.rsg` and WASM sections Ta5d6ff`meshchatx.plugin` / Ta5d6ff`meshchatx.files` / Ta5d6ff`meshchatx.signature`.

Policy:

Tff7b72- Unsigned packages are allowed

Tff7b72- Present but invalid signatures hard-block install

Tff7b72- Valid signers can be added to a user trusted-publishers list (ignored if the list file is tampered outside MeshChatX)

Tff7b72- Installed plugin trees get an integrity hash, on-disk changes disable the plugin as tampered

Sideband Python plugins are opt-in via a master danger switch. They are not ZIP-permission gated. Optional per-file Ta5d6ff`.py.rsg` signatures are verified over script bytes.

Tc9d1d9## Safe deployment patterns

Ta5d6ff```

Recommended for most users

|

v

Bind 127.0.0.1, use HTTPS, enable auth if others use the same host

|

v

Add interfaces only for meshes you trust

|

v

Keep backups and test restore on upgrades

```

Avoid exposing port 8000 directly to the internet without a reverse proxy, strong auth, and network-level filtering. MeshChatX is designed as a personal or small-team operator console, not a multi-tenant public website.

Tc9d1d9## Multi-user hosts

On shared computers, use separate OS user accounts or separate Ta5d6ff`--storage-dir` values so SQLite databases and identity files do not overlap.

Tc9d1d9## See also

Tff7b72- **Architecture and design** for session and API details

Tff7b72- **Installation and setup** for CLI security flags

Tff7b72- Reticulum manual cryptography chapters for identity math